Skip to content

docs(compliance): add capability-flag → scenario cross-reference index#4042

Closed
bokelley wants to merge 1 commit into
mainfrom
claude/issue-4039-capability-flag-scenario-cross-reference
Closed

docs(compliance): add capability-flag → scenario cross-reference index#4042
bokelley wants to merge 1 commit into
mainfrom
claude/issue-4039-capability-flag-scenario-cross-reference

Conversation

@bokelley
Copy link
Copy Markdown
Contributor

@bokelley bokelley commented May 4, 2026

Closes #4039

Summary

Adds a "Capability-gated scenarios" section to compliance-catalog.mdx that maps each get_adcp_capabilities flag to the compliance scenarios it controls. Adopters can now see at a glance how toggling a flag changes their grading surface, without grepping scenario YAMLs.

Also fixes two related correctness issues surfaced during pre-PR review:

  1. sales-proposal-mode deprecation — updates the specialism table row from stable to deprecated and adds a migration Note, matching the x-deprecated-enum-values declaration already in specialism.json. Related: docs: specialism decision tree — which sales-* specialism should I claim? #4038 also calls for this.
  2. Schema description fix — get-adcp-capabilities-response.json incorrectly stated "When false or absent, conformance runners skip proposal-lifecycle storyboards." The compliance runtime (sales-guaranteed/index.yaml) treats absent as true (scenario runs). Description updated to match.

Non-breaking justification: docs-only section addition and a schema description field fix. No wire shape changes, no required fields added, no enum values altered. The schema "default": false is preserved; only the prose description is corrected.

Pre-PR review

  • code-reviewer: approved — flagged the schema/runtime description contradiction as a blocker; fixed in get-adcp-capabilities-response.json. One nit on table cell wording; addressed.
  • docs-expert: approved with nits — table cell "Default (when absent)" wording clarified to "treated as true — runs (graded)"; sales-proposal-mode purpose cell trimmed to match column length discipline.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout 4039 →
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_014X1pXA976RomzNxWUC4ei9

Generated by Claude Code

@claude
docs(compliance): add capability-flag → scenario cross-reference index
d20b94c 
Adds a "Capability-gated scenarios" section to compliance-catalog.mdx
mapping each get_adcp_capabilities flag to the scenarios it controls,
so adopters can see at a glance how a flag toggle changes their grading
surface without grepping scenario YAMLs.

Also fixes two related issues in the same file and schema:

- Updates sales-proposal-mode specialism status to deprecated (matching
  the x-deprecated-enum-values declaration in specialism.json)
- Fixes the supports_proposals schema description, which incorrectly
  stated "absent" means skip; the compliance runtime treats absent as
  true (per sales-guaranteed/index.yaml), so the description now reads
  "When absent, the compliance runner treats the flag as true"

Closes #4039.

https://claude.ai/code/session_014X1pXA976RomzNxWUC4ei9
@bokelley bokelley mentioned this pull request May 4, 2026
Closed
@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label May 4, 2026
@bokelley
Copy link
Copy Markdown
Contributor Author

bokelley commented May 11, 2026

Closing — docs-expert review found this PR contradicts the schema-accurate #4044 on two load-bearing facts:

  1. Skip-reason vocabulary fabricated: table uses capability_unsupported which is not in the canonical skip_result.reason enum in runner-output-contract.yaml (the canonical values are not_applicable | no_phases | prerequisite_failed | missing_tool | missing_test_controller | unsatisfied_contract | peer_branch_taken | requirement_unmet). docs(compliance): explain how grading works end-to-end (#4037) #4044 correctly uses not_applicable. Shipping both would publish contradictory grading codes in adjacent docs pages.

  2. Absent-flag semantics contradict the schema default: this PR says "absent → treated as true (runs)" and edits the schema description to match; docs(compliance): explain how grading works end-to-end (#4037) #4044 and the JSON schema default: false say absent → skip. The schema is the source of truth.

  3. Hand-maintained table for one row (media_buy.supports_proposals) — drift-prone on day one. If we want a cross-reference index, it should be generated from requires_capability blocks across scenario YAMLs.

Recommend redoing as either (a) drop the table, or (b) generate it from source. The sales-proposal-mode deprecation update inside this PR is independently fine and can ship as its own small PR if useful.

@bokelley bokelley closed this May 11, 2026
@bokelley
Copy link
Copy Markdown
Contributor Author

bokelley commented May 11, 2026

All three corrections are well-founded. The capability_unsupported enum fabrication and the absent-flag contradiction with "default": false are load-bearing — right call to close rather than patch.

For the sales-proposal-mode deprecation: #4038 already carries the explicit "do not claim sales-proposal-mode for new agents" ask, so that fix will land when #4038 is actioned without needing a separate PR.

#4039 stays open for the generated-index approach. Comment /triage execute on it when the generated approach is ready to build.

Claude Code — Session: https://claude.ai/code/session_01AWZZv5b5cfzvsU2MCeqMVa

Generated by Claude Code

This was referenced May 11, 2026
Open
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: capability flag → scenario cross-reference ("what does this flag turn on/off?")

2 participants

@bokelley @claude